# PMG Relay Framework

# Relay Framework Overview

The PMG Relay Framework is a solution which enables a PMG instance in one network to execute PMG workflows and PowerShell activities in a remote network and receive results. The framework is comprised of a stack of applications, services and workflow activities which support remote communications with configurable ports as well as support for web sockets which can significantly alleviate the need for firewall changes or VPN setup. Any number of remote network agents may connect to any number of "relay/listening service(s)" to support a many-to-many setup of remote agents and PMG Workflow instances.

There are three main components in the relay framework. The PMG “Workflow Engine”, which orchestrates the work to be done in PowerShell or a PMG Workflow Function on a network for which the engine cannot access. The PMG “Relay Service”, which provides a communications layer between the “Workflow Engine” and the “Remote PowerShell Agent”. “Remote Agent”, a service which runs on a computer within an isolated network, which will listen for commands to be ran from the “Workflow Engine”.

Relay Framework Diagram

# Workflow Engine Remote PowerShell Action

The Remote PowerShell Action is used within a PMG workflow to specify the target agent and desired script to be executed. Credentials for the remote script are specified within the remote agent connection scenario. See Execution Scenario for details. Once connectivity is established, The PMG Workflow issues commands to the remote agents as needed.

* Persistent connections use WebSockets for connectivity. WebSocket connections can leverage proxy services, and agents must be installed to Windows 2012 or higher.

** The PowerShell Data Bus is a virtual data bus scoped to an executing workflow instance which allows for persistent storage of information between executing PowerShell scripts. See PMG PowerShell Remote Agent Cmdlets.

+ connections are encrypted with AES256 using configurable shared secret password. Network ports are configurable.

The PMG Relay Framework allows for communications between two isolated networks given the following. Network A, the target network, has no inbound or limited inbound communications available. Network A may also have limited outbound network traffic, firewalled to specific network port access, or outbound access granted only by a proxy service.

However, given Network A can communicate outbound via proxy or firewall, the PMG Relay Service allows the PMG Workflow Engine, from Network B, the source network, to send commands to be executed to the target environment.

In this case, to execute PowerShell within the remote network, the PMG Remote Agent will need to be deployed and configured to establish an outbound "channel" connection request to the PMG Relay Service. The remote agent will register itself with a unique identifier, typically the machine name. The agent identifier, or "agent name" will be used by the PMG Workflow Engine to specify the target for the remote commands. Commands are sent to the PMG relay service which then forwards the commands to the listening matching agents.

The remote agent will keep its connection open as well as implement a "keep alive" and a "connection refresh" process. The connection will be used for the agent to listen for new commands from the "relay service".

A Remote PowerShell action will attempt to connect to the relay server synchronously to transmit the request. The relay service will receive the request and look for a matching registered remote agent name. If no match is found, the action will follow out "Remote agent not found".

If a matching agent is registered with the relay service, the service will transmit the request to the agent. The remote agent will attempt to execute the request synchronously and its response will be sent to the relay service, to be transmitted back to the originating workflow engine.

# PMG Relay Framework Requirements

The below provides requirements for the components of the PMG Relay Framework

# Remote Agent

Remote Agents may be installed to Window Server 2012 or higher, with PowerShell 5.1 or higher. Remote Agents may also be installed to Linux with PowerShell Core 2 or higher. Windows Management Framework 5.1 or higher may be required on Windows Server versions prior to 2016. See WMF 5.1 at https://go.microsoft.com/fwlink/?linkid=839460

The remote agent server requires network or proxy access to the PMG Relay Service. Proxies must support WebSockets.

# PMG Relay Service

Windows Server 2012 or higher with IIS. May optionally be deployed on one or more PMG Portal instances. The relay service must be network accessible to both the Remote Agent and the PMG Workflow Engine server.

# PMG Workflow Engine / Remote PowerShell Action

The PMG Workflow engine requires network or proxy access to the PMG Relay Service. Proxies must support WebSockets.

# Remote Agent and Relay Service Installation

The below instructions apply to installation of each feature, the Remote Agent and the Relay Service

Run the WorkflowRemoteAgent.exe file to extract its contents to a specified folder.
Select the extraction path and click OK. Note: The default extract path is C:\Program Files\PMG Service Catalog\WorkflowRemoteAgent\

Run the program RelayAgentConfigGUI.exe in the extract folder selected

Note: Once configured, the Relay and Agent services are accessible as needed as an installed Windows Service.

# Agent/Relay Settings

To configure the machine as an Agent, check “Enable Agent” and provide the following.

Agent Name: a unique name for the agent, which will be referenced from a workflow.

Replay IP: the machine name or IP address of the Relay Service server

Agent Port: the Agent Port to use when connecting to the Relay Server. Note: Workflow Port is ignored for Remote Agents.

If the agent requires a proxy to connect to the relay server, provide values for “Agent Proxy Settings”

Server: the Proxy Server for the outbound connection

Port: the Proxy Server port to use

User/Domain/Password: optional user information for the proxy server access

To finalize the Agent configuration, Click “Apply” button to save configuration then “Start Services” to start the PMG Remote Agent Service

To configure the machine as a Relay, check “Enable Relay” and provide the following.

Relay IP: the Relay IP for the Relay Service to bind for listening

Agent Port: the Agent Port which the Relay Service will listen for remote Agent connections

Workflow Port: the Workflow Port which is the IP port the Relay Service will listen for PMG Workflow connections

WebSocket Proxy Settings are ignored for the Relay Service

Click “Apply” to save the configuration, then click “Start Services” to start the PMG Relay Service

# Remote Workflow Support

The Database tab of the configuration application is required to execute workflows

Provide values as needed to communicate with the PMG database and click “Update”

# Connection Diagnostics

The Relay Query tab provides diagnostic information for the configured services. Click “Query” to receive information about the connection.

# Remote Agents

Remote agents are available in two forms, as PowerShell agents and Workflow Function agents. The PMG Remote PowerShell agent operates as lightweight specialized software package which can listen for and execute PowerShell with various security contexts, and in parallel execution. The PMG Workflow Function Agent is an instance of a PMG Workflow Server configured to listen for workflow functions to be executed and return results. PowerShell agents are available for Windows and Linux with PowerShell Core.

The “Remote Agent” is a service which listens for PowerShell commands (Windows or Linux) or Workflow Functions (Windows) to be ran on the agent. Commands can be local to the specified computer or outbound to another computer or application.

# Relay Service

The Relay Service runs as a Windows Service and can be deployed independently or within another PMG application server. The PMG Workflow Engine and Remote Agents communicate with the Relay Server by available Proxy services or through configured TCP ports.

When an agent connects, the agent registers with its configured instance name. See Remote Agent Configuration for details. This agent instance name will subsequently be used by the PMG Workflow Engine as the requested “Scenario” by either the Remote PowerShell Action or Remote Workflow Action.

# High Availability

The framework supports a high availability configuration to allow for resilience and uptime, while also enabling the removal of instances from the pool in order to perform any system maintenance. See the Execution Scenario information for how to specify a pool of relay servers and a pool of agents.

When stopping an agent service or a relay service, the service will attempt to allow any current processes to complete. This allows individual relays or agents to be removed from a group or farm as needed.

# Remote PowerShell Action Usage

# Remote PowerShell

PMG Workflow offers the “Remote PowerShell” action to initiate PowerShell commands to remote registered agents.

The action is found under the Integration category in the actions palette. The action properties are as follows.

Name

Provides for a friendly custom name for the action within the diagram

Label

Provides for an additional text label for the action within the diagram

Run Mode

This setting determines how the PowerShell will be executed.

New Process: The PowerShell will run within a separate execution scope, with the security context of the running service

New Process (As User): The PowerShell will run in as the user identity specified in the given scenario

Execution Scenario

Specifies the execution scenario, managed from the Designer Menu Bar, Manage, Connector Configuration, ExecuteAs.Config.xml.

An example scenario is below.

<actionconfig>
    <scenario name="machineA">
        <!-- name:Specifies the name of the scenario to be used by the workflow action -->
        <relayServerCommMode>WebSocket</relayServerCommMode>
        <!-- Specifies the communications mode for the relay. If the node value is WebSocket, then WebSockets will be used for the connection. Otherwise, standard TcpClient is used. -->
        <useRelayServer>true</useRelayServer>
        <!-- When the node is “true”, specifies the connection will use a Relay Server, or if “false” or not present, then a direct TCP connection will be made. -->
        <proxyServer /><!-- Optional proxy server machine name or IP address -->
        <proxyPort /><!-- Optional proxy port to use -->
        <proxyUser /><!-- Optional proxy user if credentials are required -->
        <proxyDomain /><!-- Optional user domain for credentials if required -->
        <proxyPassword /><!-- Optional proxy password if required -->
        <relayConfig>
            <!-- NOTE: Multiple relayConfig nodes may be defined to specify a list of relays to try.This node specifies attributes for the relay server -->
            <ip>127.0.0.1</ip><!-- Specifies the machine name or IP address of the relay server -->
            <workflowPort>17001</workflowPort><!-- Specifies the network port of the Workflow Engine -->
            <retryDelayMs>1000</retryDelayMs><!-- Optional delay in milliseconds to retry a communication request -->
            <agentWaitMs>30000</agentWaitMs>
            <!-- Optional time in milliseconds to wait for a remote command to execute -->
        </relayConfig>
        <agentName>machineA</agentName>
        <!-- NOTE: multiple agentName nodes may be specified to establish a pool of agents to try to send commands -->
        <domain>DOMAIN</domain><!-- The domain name for the user to authenticate for the remote command -->
        <username>USERNAME</username><!-- The username to authenticate the remote command -->
        <password note="thisIsMethod2">Q…AA==</password>
        <!--The password of the remote user to authenticate the remote command -->
        <waitseconds>600</waitseconds>
        <!--The time to wait in seconds for the command to execute. -->
        <certName>Workflow Remote Agent Server</certName>
        <!-- The name of the certificate to be used when using TcpClient. The cert must be installed in the Personal folder for the local machine -->
        <authKey>qi…m</authKey> <!-- a shared secret key -->
    </scenario>
    <actionconfig>

Script

The Script property contains the script to run on the remote server. The editor provides a PowerShell syntax aware editor as below. The script supports accessing and setting PMG workflow variables, which then effectively provides a PowerShell data bus for any scripts ran within the workflow.

Variable for Information

Optional string variable to capture “Information” level pipeline details

Variable for Error

Optional string variable to capture “Error” level pipeline details

Action Outputs

This action will output one of the following

Successful – The remote PowerShell or action was able to execute (with or without PowerShell script errors)

Unsuccessful – The Relay Framework encountered some issue in attempting to transmit or receive the information for the requested PowerShell script.

Agent Not Found – The Relay Framework did not find a matching agent available to process the requested PowerShell script

# PMG variables and PowerShell variables

PMG variables and PowerShell variables may be used interchangeably within the defined script. In the example above, a PMG variable $RemoteCounter is referenced and modified within the script. This updated value will become the new value of $RemoteCounter within the PMG workflow on completion of this action execution. The updated value can then be referenced later within the same workflow, as well as be referenced in a subsequent Remote PowerShell action.

Remote PowerShell may also leverage encrypted Environment Values.

# PMG PowerShell Cmdlets

The PMG Remote Agent makes the following cmdlets available.

# Get-PMGSecureString – NOTE: This cmdlet is flagged for deprecation. Please use encrypted Environment Variables as the alternative. See [Securing Credentials](#Securing Credentials) for Remote PowerShell usage

# Add-PMGStepDetail

This cmdlet will log information back to the executing action step details

An example test script is below.

Add-PMGStepDetail -Message "some stuff!"

# PMG PowerShell Cmdlets - deprecated

NOTE: The following PMG PowerShell Cmdlets are deprecated and are replaced with inline variable access.

The PMG Remote Agent is installed with PowerShell cmdlets which support the getting and putting of values into PMG workflow variables.

Get-PMGVariable -name

This cmdlet will load a variable value from the PMG workflow instance

Set-PMGVariable

This cmdlet will set a value back to a PMG workflow variable

# Securing credentials for Local and Remote PowerShell usage

Values may be stored encrypted and secured locally, within the PMG application and then made available for access to local and remote PowerShell execution.

To secure data for PowerShell, follow the below steps.

Define an environment value using the "Encrypt" feature.
To further secure a value for PowerShell, you may limit which workflows can access the environment value using the "Change associated workflows" setting for the value.

An encrypted and limited environment value will appear as below in the Environment Values screen.

Secured Env Value Example

To access the secured value from PowerShell, refer to the value as a variable using $ASecuredValue, based on the example above.

# Legacy Method

Note: This below method is deprecated. Please use encrypted Environment Values instead.

To use a secure string with the Get-PMGSecureString cmdlet in the the PowerShell action, follow the below steps.

The Get-PMGSecureString requires a connector configuration to access encrypted data. To create a new secure string, From the PMG Workflow Designer, navigate to the Connector Configuration utility.

If PowerShell.Config.xml is available in the connector configuration dropdown, skip to the PowerShell.Config.XML example. Otherwise, to create a new Connector Configuration, click new.

Create a configuration with the name “PowerShell.Config.xml”

# PowerShell.Config.XML example

Add the XML below to your configuration. Proceed to step 6.

<powershell>
    <securedata> <data name="{{name}}">
            <workflows>
                <workflow>{{workflowname}}</workflow>
            </workflows>
            <securestring>{{__method2_encrypted_data__}}</securestring>
        </data> </securedata>
</powershell>

To add more secure string options to your configuration add a repeating data node.

<powershell>
    <securedata>
        <data name="MyPassword">
            <workflows>
                <workflow>PS_GetAccounts</workflow>
                <workflow>PS_SecureString</workflow>
            </workflows>
            <securestring>AwC0AM8AICAXADMAXgB9AEIAQQALAA/AAEAYAH</securestring>
        </data>
        <data name="{{name}}">
            <workflows>
                <workflow>{{workflowname}}</workflow>
            </workflows>
            <securestring>{{__method2_encrypted_data__}}</securestring>
        </data>
    </securedata>
</powershell>

Replace with the name you’d like to use to refer to your secure string, such as AzurePassword.

Replace with the name of the workflow you’d like to have access to this data. More workflow nodes can be added to use this secure string in other workflows.

<workflows>
    <workflow>{{workflowname1}}</workflow>
    <workflow>{{workflowname2}}</workflow>
</workflows>

Replace

{{__method2_encrypted_data__}}

with the encrypted data you’d like to use as your secure string. Use PMG’s method 2 to perform the encryption.

Click “Save” at the bottom right of the window.

This data can now be used in the PowerShell action’s PowerShell Script property.

You can refer to this data in the PowerShell Script property as shown below.

$password = Get-PMGSecureString -name MyPassword

$UserCredential = New-Object System.Management.Automation.PSCredential ("bob@bob.com", $password)

Login-AzureRmAccount -Credential $UserCredential

This data is retrieved with the Get-PMGSecureString cmdlet. Refer to the data you want with the name you provided in the PowerShell.Config.XML above

# Remote Workflow Action

The Remote Workflow Action leverages the PMG Relay Framework to execute a workflow function from a configured Remote Workflow Agent. To “pass” or “receive” data in the remote workflow, use variables of the same name in both workflows. If both workflows have a string variable named, “MyString”, and the calling workflow sets MyString to “Are You There”, then that value will be automatically available in the called workflow function in the variable of the same name. The called workflow function can then change the value, to “Yes” which would then be available to the calling workflow.

NOTE: This action requires access to the application database.

The action provides the following properties.

Scenario – This determines the remote agent name which will execute the workflow function. Scenarios are defined within the ExecuteAs.Config.xml connector configuration.

Workflow – Specifies the workflow name to be executed

Use as Synch Result – Determines if the output of the called workflow function will be used as the synchronous result of the calling workflow

Send Content XML – Determines whether the contents of the calling workflow will be used as the contents of the remote invoked workflow function

# External Data Sources over Relay Framework

The Relay Framework supports connectivity to external data sources. The PMG Platform is able to query external data sources through the agents which have access to the given data source. As an example, this connectivity provides access of a cloud hosted PMG instance to query data sources which are located behind a corporate firewall on a private network. To enable this feature, see the setting ENABLE_REMOTE_DATA_SOURCES. Once enabled, forms, apps, workflows, reports, etc. may access the remote data source.

With the feature enabled, there is a new setting configuration for "External Data Sources" to set the Remote Data properties.

← Data Protection System Settings →